
Using ViSta's PLOT objects and PLOTS menu

ViSta's PLOTS menu is used to generate individual plots. The nature of each plot is discussed in the help information for the individual plot itself. 

The plots are generated by a function called the plot constructor function. You can also generate the plot by typing the function into the listener. Whereas the item in the PLOT menu generates a default plot, you can gain a lot of control over the nature of each plot by typeing the plot's constructor function. The details of how to do this are discussed below.

The name of each of the various plot constructor functions is identical to the menu-item's name, except that spaces in the menu-item name are replaed by dashes in the constructor function. That is, the "Scatter Plot" menu item corresponds to the SCATTER-PLOT constructor function. 

Each constructor function may have an optional DATA argument and may have several KEYWORD arguments. If no arguments are used, a default plot is constructed which is the same as the plot generated by the PLOTS menu's menu item. This default is constructed from information in $, the current data. The information that is used is the first few variables in the list of all variables. Only the appropriate variable types are used. The number of vectors that are used depends on the details of the plot, as does the definition of the appropriate variable types. The default plot will include variable-labels and point-labels (or way-labels and level-labels), and will have a button-bar, a pop-up menu, a title and legends. The plot will appear in its' own window (i.e., not inside a container window), although the menu system may override this default.
 
All plots share the following arguments and syntax:

    (PLOT-CONSTRUCTOR-NAME 
        &optional DATA 
        &key      KEYWORD-ARGUMENTS)

ABOUT THE DATA ARGUMENT
The optional DATA argument may be omitted or may be NIL, or it may be a data object, a list of numeric or string elements, a list of variable objects, a list of equal-length lists, a vector, a list of equal-length vectors, or a matrix. If omitted or NIL, DATA is assumed to be $, the current dataobject. In all cases, DATA is converted into a list of equal-length vectors. one vector for each of the OK-VAR-TYPES (see below) variables in the referenced data object.

The plot is constructed from the first few vectors in the list of vectors, the number of vectors depending on the details of the plot. If you need to use any of the keyword arguments, the data must be specified, and it must be mentioned before the keywords.

ABOUT THE KEYWORD ARGUMENTS
The keyword arguments consist of STANDARD keyword arguments (which are used by all of the plots and which are discussed here) and UNIQUE keyword arguments (which are unique to each plot and which are discussed in the help for each plot). If you need to use any of the keyword arguments, the data must be specified (perhaps as nil or $) before the keywords are specified. 

The standard keyword arguments (with defaults in parentheses, if appropriate) are:

ok-var-types    a list of symbols or strings 
                of usable variable types

variable-labels a list of strings, one for each variable 

point-labels    a list of strings, one per point 

in (unused)     T, NIL, (UNUSED) or CONTAINER - 
                sets the container window.

linked (T)      T or NIL for linked with other plots 
                via stat object (not for comparison-plot, 
                mosaic-plot or bar-graph)

connect (NIL)   T or NIL for connecting points with lines
                (not for histogram-plot, mosaic-plot or bar-graph)

show (T)        T or NIL controls if plot shown when created

top-most (T)    T or NIL sets whether plots are on top

location        a list (x y) locating the plot's upper-left 
                corner 

size            a list (w h) of the plot's width & height 

title           a string shown in the graph window title bar 

legend1         a string for the first line of the legend 

legend2         a string for the second line of the legend

content-only    T or NIL sets if only plot content shown

VARIABLE-LABELS and POINT-LABELS
Variables and points can be labeled with the VARIABLE-LABELS and POINT-LABELS keywords.  (bar-graphs and mosaic plots use WAY-LABELS and LEVEL-LABELS). Each argument is followed by a list of the appropriate number of strings. 

IN
By default, each plot will appear as an independent window (i.e., not inside a container window) when it is created. If :IN is used, the new graphic will appear inside a container window. If a menu item is used to create the graphic, IN will be set by the menuing system to direct the graph to the appropriate container.The container will be:
  1: CONTAINER if IN is CONTAINER
  2: XLISPSTAT if IN is NIL 
  3: *ACTIVE-CONTAINER* if IN and *ACTIVE-CONTAINER* are T
Note that for case 3 it can be tricky to determine where the graph appeared if the container is not visible.

SHOW, LOCATION, SIZE, TOP-MOST
The plot will not be shown when :SHOW is NIL until it is sent the message :SHOW-WINDOW. When the window appears it will be be at LOCATION (which is relative to the window's container, if there is one) and be of size SIZE. The graphic will be :TOP-MOST by default. Note that the graphic will not be seen when it appears if its containing window is closed, minimized, located off-screen, or obscurred by another window.

TITLE, MENU, LEGEND1, LEGEND2 and CONTENT-ONLY
Each plot can have a menu, title, and two legends. When :CONTENT-ONLY is T there will be no overlays, button-bars, legends, etc., which is useful if the graph is part of a large spreadplot. 

ABOUT THE MENUS

All old-style graphics and all new-style plots now use the message :make-two-plot-menus, to invoke a graph-proto method which creates the several plots menus and the do-click method that causes the menus to appear. This message and its associated method are invoked by a rewritten version of Luke's :new-menu message/method (see page 290 of Tierney). Since :new-menu is invoked by every graph-proto's :isnew method, so is :make-two-plot-menus.

Note that the :make-two-plot-menus method really only constructs one menu, since a window can only have one menu. It looks like two menus are made, but really it is one menu which has two sets of items, one presented as a popup to a right-click, the other as a pull-down from the menu-hotspot. The do-click method determines which set of items should be presented. The code for :make-two-plot-menus and the revised code for :new-menu is in runtime\graphic1.lsp. 

The :make-two-plot-menus method makes two sets of menu items. The selection of menu items in the set is determined by the :menu-template and :popup-menu-template methods, which return a selection of menu template symbols. You can change the selection of menu items by modifying a plot's :menu-template and :popup-menu-template methods, as outlined by Luke. You can also use the :make-two-plot-menus message itself. For example, scatterplots might have the following use of the message:

(send self :make-two-plot-menus 
        "Scatter"
        :hotspot-items  '(help dash new-x new-y dash link dash
                          on-top maximize dash print save copy))
        :popup-items '(showing-labels mouse resize-brush dash
                       erase-selection focus-on-selection view-selection
                       select-all show-all dash
                       symbol color dash 
                       selection slicer))

The hotspot-items and popup-items lists are lists of symbols which are defined in accordance with Tierney's discussion of menu templates. You can get a list of the hotspot menu items defined for a graph by typing (send graph :menu-template). The popup-items for a graph can be listed by typing (send graph :popup-menu-template). You can get a list of the entire set of items which I have defined up to this point by typing (menu-symbols). This list is not updated if you add more. Not all items work. The code is in file runtime\graphics0.lsp. 

To add items to the menus, you should add symbol definitions to the make-menu-template method near the end of the runtime\graphics1.lsp file. It is also a good idea to add the symbol to the (menu-symbols) function nearby. Of course, you also have to define the method or function used by the item. Then you have to add the symbol to the appropriate template as summarized below. You have to do for each plot or graphic that is to have the new item.

For the old-style graphics, the message appears in the :isnew method (or sometimes in another method used by the :isnew method) for each graph or in a specifically mentioned template. The message's location, for each old-style graph is given here:

GRAPH CONSTRUCTOR FUNCTIONS     WHERE TO ADD MENU ITEMS
histogram
histofreq                       histofreq-proto :isnew in histfrq1.lsp  
quantile-plot                   quantile-plot-proto :isnew in qplotobj.lsp  
normal-probability-plot         quantile-plot-proto :isnew in qplotobj.lsp  
quantile-quantile-plot          quantile-quantile-plot-proto :isnew in qplotobj.lsp
plot-points                     vista-scatterplot-proto :revised-look-and-feel and
                                scatterplot-proto :vista-look-and-feel in scatter1.lsp
spin-plot                       spinplot-proto :isnew in spinplot.lsp
scatterplot-matrix              scatmat-proto :menu-template  in scatmat.lsp


mosaic-plot                     

For the new-style plots, the message appears in the constructor function, overriding the old-style graphics usage of the method to reflect the added features of the new plots. The message's location, for each plot, is given here:)

PLOT CONSTRUCTOR FUNCTIONS      WHERE TO ADD MENU ITEMS
histogram-plot
distribution-plot               distribution-plot function   in plots002.lsp 
cumulative-plot                 cumulative-plot function     in plots002.lsp 
comparison-plot                 comparison-plot function     in plots002.lsp 
dot-plot                        dot-plot function            in plots001.lsp 
scatter-plot
all-scatter-plots               all-scatter-plots function   in plots001.lsp 
spinning-plot                   spinning-plot function       in plots001.lsp 
orbit-plot                      orbit-plot function          in plots001.lsp 
line-plot                       line-plot function           in plots001.lsp
box-plot                        box-or-diamond-plot function in plots004.lsp
diamond-plot                    box-or-diamond-plot function in plots004.lsp
subgroups-plot                  subgroups-plot function      in plots004.lsp
parallel-coords-plot            box-or-diamond-plot function in plots004.lsp
bar-graph                       bar-graph-new function       in plots003.lsp
mosaic-plot                     mosaic-plot-new function     in plots003.lsp




